\subsection{由 GL 渲染緩衝創建 CL 圖像對象}

\topclfunc{clCreateFromGLRenderBuffer}

\startCLFUNC
cl_mem clCreateFromGLRenderbuffer (
			cl_context context,
			cl_mem_flags flags,
			GLuint renderbuffer,
			cl_int *errcode_ret)
\stopCLFUNC

此函式可以由 OpenGL 渲染緩衝對象創建 OpenCL 2D \cnglo{imgobj}。

\carg{context} 是一個由 OpenGL \cnglo{context}創建的 OpenCL \cnglo{context}。

\carg{flags} 是位欄，用於指定用法資訊。參見\reftab{clmemflags}。
此處只能使用 \cenum{CL_MEM_READ_ONLY}、 \cenum{CL_MEM_WRITE_ONLY} 和 \cenum{CL_MEM_READ_WRITE}。

\carg{renderbuffer} 是 GL 渲染緩衝對象的名字。
創建\cnglo{imgobj}前必須先指定渲染緩衝的存儲。
OpenGL 為 \carg{renderbuffer} 定義的格式和維度
會被用來創建 2D \cnglo{imgobj}。
僅當 GL 渲染緩衝對象的內部格式可以映射到
\reftab{imgChannelOrder}和\reftab{imgChannelDataType}中所列通道次序和數據型別時，
才可用來創建 2D \cnglo{imgobj}。

\carg{errcode_ret} 會返回相應的錯誤碼，見下文。
如果他是 \cmacro{NULL}，則不會返回錯誤碼。

如果成功創建了\cnglo{imgobj}，則 \clapi{clCreateFromGLRenderbuffer} 會將其返回，
並將 \carg{errcode_ret} 置為 \cenum{CL_SUCCESS}。
否則，返回 \cmacro{NULL}，並將 \carg{errcode_ret} 置為下列錯誤碼之一：
\startigBase
\item \cenum{CL_INVALID_CONTEXT}，
如果 \carg{context} 無效，或者不是由 GL \cnglo{context}創建的。

\item \cenum{CL_INVALID_VALUE}，如果 \carg{flags} 的值無效。

\item \cenum{CL_INVALID_GL_OBJECT}，
如果 \carg{renderbuffer} 不是 GL 渲染緩衝對象；
或者 \carg{renderbuffer} 的寬或高是零。

\item \cenum{CL_INVALID_IMAGE_FORMAT_DESCRIPTOR}，
如果 OpenGL 渲染緩衝內部格式不能映射到所支持的 OpenCL 圖像格式上。

\item \cenum{CL_INVALID_OPERATION}，
如果 \carg{renderbuffer} 是多重採樣的 GL 渲染緩衝對象。

\item \cenum{CL_OUT_OF_RESOURCES}，如果\scdevfailres。

\item \cenum{CL_OUT_OF_HOST_MEMORY}，如果\schostfailres。
\stopigBase

如果存在對應的 CL \cnglo{imgobj}，
但是通過 GL API （如用 GL API \capi{glRenderbufferStorage}
 修改了用以表示 GL 渲染緩衝像素的維度或格式）
修改了 GL 渲染緩衝對象的狀態，
則後續使用 CL \cnglo{imgobj}時會導致\cnglo{undef}的行為。

可使用函式 \clapi{clRetainMemObject} 和 \clapi{clReleaseMemObject} 來
\cnglo{retain}和\cnglo{release}此\cnglo{imgobj}。

\reftab{ImgFmtMap}列出了 GL 渲染緩衝內部格式與 CL 圖像格式間的對應關係。
只要 GL 寫入緩衝對象是\reftab{ImgFmtMap}中所列格式，就保證能將其映射到表中對應的 CL 圖像格式上。
如果渲染緩衝對象是其他 OpenGL 內部格式，
則可能（但不保證）也能映射到 CL 圖像格式上；
如果存在這樣的映射，則保證保留所有顏色組件、數據型別，並且每個組件的位數至少與分配 OpenGL 對象時相同。

